home *** CD-ROM | disk | FTP | other *** search
/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / IDE / SUBARTIC / SUB_ARCT / INPUT / SNAP_DRA.JAV < prev    next >
Encoding:
Text File  |  1996-10-04  |  9.5 KB  |  212 lines
  1.  
  2. package sub_arctic.input;
  3.  
  4. import sub_arctic.lib.interactor;
  5. import java.awt.Point;
  6.  
  7. /** 
  8.  * This interface provides the input protocol for objects which are dragged
  9.  * and may be snapped to objects which implement the snap_targetable 
  10.  * interface.  (This is a subclass of move_draggable.)  These "drag" objects 
  11.  * are moved over the top of snap "target" objects.  Where the right 
  12.  * conditions occur, feedback is produced which snaps the objects together in 
  13.  * some way (typically by pulling the drag object to the target object). 
  14.  * The snap is said to occur "from" drag (snap_draggable) objects "to" target 
  15.  * (snap_targetable) objects.  Both this protocol and the snap_targetable 
  16.  * protocol are managed and delivered by the snap_drag_agent.<p>
  17.  *
  18.  * Snapping requires a two part test.  The first part is geometric.  In this 
  19.  * part we determine if a feature point of the drag object is close enough
  20.  * geometrically to snap to the target.  If this test passes, then a second
  21.  * semantic test is performed to determine if the two objects are semantically
  22.  * compatible (this second test by snap_targetable.snap_from_ok() may involve 
  23.  * type tests and/or exchange of information between the target object and this
  24.  * object using the protocol of an application specific interface defined
  25.  * elsewhere).  If both snapping tests succeed, and the snap is the closest 
  26.  * candidate snap,  the snap will occur.<p>
  27.  * 
  28.  * If their are no suitable snaps, but some snaps pass the geometric test 
  29.  * (i.e., are close enough) then "anti-snaps" will be considered.  An 
  30.  * anti-snap is designed to provide feedback about a negative condition -- 
  31.  * it is typically used to produce a kind of dynamic "error message" that 
  32.  * indicates why a geometrically possible snap is not semantically suitable.  
  33.  * Anti-snaps must pass a second semantic test (performed by 
  34.  * snap_targetable.anti_snap_from_ok()) before they are activated.<p>
  35.  *
  36.  * @see sub_arctic.input.move_draggable
  37.  * @see sub_arctic.input.snap_targetable
  38.  * @see sub_arctic.input.snap_drag_agent
  39.  * @author Scott Hudson
  40.  */
  41. public interface snap_draggable extends move_draggable {
  42.  
  43.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  44.  
  45.   /** 
  46.    * Indicate that the object should snap to a given target object. 
  47.    *
  48.    * @param event           evt             the event "causing" the snap.
  49.    * @param Point           orig_pt         where this object would be without 
  50.    *                                        the snap.
  51.    * @param Point           snap_pt         where this object is with the snap.
  52.    * @param int             feature_pt_indx the feature point of this object 
  53.    *                                        that we are snapping with.
  54.    * @param snap_targetable target_obj      the target object we are snapping 
  55.    *                                        to.
  56.    * @param Object          user_info       the user info for this input.
  57.    * @return boolean indicating if the input has been consumed.
  58.    */
  59.   public boolean snap_to(
  60.     event           evt,
  61.     Point           orig_pt,
  62.     Point           snap_pt,
  63.     int             feature_pt_indx,
  64.     snap_targetable target_obj,
  65.     Object          user_info);
  66.  
  67.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  68.  
  69.   /** 
  70.    * Perform feedback while a snap is active.
  71.    *
  72.    * @param event           evt             the event "causing" the snap.
  73.    * @param Point           orig_pt         where this object would be without 
  74.    *                                        the snap.
  75.    * @param Point           snap_pt         where this object is with the snap.
  76.    * @param int             feature_pt_indx the feature point of this object 
  77.    *                                        that we are snapping with.
  78.    * @param snap_targetable target_obj      the target object we are snapping 
  79.    *                                        to.
  80.    * @param Object          user_info       the user info for this input.
  81.    * @return boolean indicating if the input has been consumed.
  82.    */
  83.   public boolean snap_feedback(
  84.     event           evt,     
  85.     Point           orig_pt,
  86.     Point           snap_pt,
  87.     int             feature_pt_indx,
  88.     snap_targetable target_obj,
  89.     Object          user_info);
  90.  
  91.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  92.  
  93.   /** 
  94.    * Indicate that the object is no longer snapped to a given target object.
  95.    *
  96.    * @param event           evt             the event "causing" the unsnap.
  97.    * @param Point           orig_pt         where this object should be without 
  98.    *                                        the snap.
  99.    * @param Point           snap_pt         where this object was with the snap.
  100.    * @param int             feature_pt_indx the feature point of this object 
  101.    *                                        that we were snapping with.
  102.    * @param snap_targetable target_obj      the target object we were snapping 
  103.    *                                        to.
  104.    * @param Object          user_info       the user info for this input.
  105.    * @return boolean indicating if the input has been consumed.
  106.    */
  107.   public boolean unsnap_to(
  108.     event           evt,
  109.     Point           orig_pt,
  110.     Point           snap_pt,
  111.     int             feature_pt_indx,
  112.     snap_targetable target_obj,
  113.     Object          user_info);
  114.  
  115.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  116.  
  117.   /** 
  118.    * Indicate that the object should anti-snap to a given target object. 
  119.    *
  120.    * @param event           evt             the event "causing" the anti-snap.
  121.    * @param Point           orig_pt         where this object would be without 
  122.    *                                        the anti-snap.
  123.    * @param Point           snap_pt         where this object is with the 
  124.    *                                        anti-snap.
  125.    * @param int             feature_pt_indx the feature point of this object 
  126.    *                                        that we are anti-snapping with.
  127.    * @param snap_targetable target_obj      the target object we are 
  128.    *                                        anti-snapping to.
  129.    * @param Object          user_info       the user info for this input.
  130.    * @return boolean indicating if the input has been consumed.
  131.    */
  132.   public boolean anti_snap_to(
  133.     event           evt,
  134.     Point           orig_pt,
  135.     Point           snap_pt,
  136.     int             feature_pt_indx,
  137.     snap_targetable target_obj,
  138.     Object          anti_snap_info,
  139.     Object          user_info);
  140.  
  141.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  142.  
  143.   /** 
  144.    * Perform feedback while an anti-snap is active.
  145.    *
  146.    * @param event           evt             the event "causing" the anti-snap.
  147.    * @param Point           orig_pt         where this object would be without 
  148.    *                                        the anti-snap.
  149.    * @param Point           snap_pt         where this object is with the 
  150.    *                                        anti-snap.
  151.    * @param int             feature_pt_indx the feature point of this object 
  152.    *                                        that we are anti-snapping with.
  153.    * @param snap_targetable target_obj      the target object we are 
  154.    *                                        anti-snapping to.
  155.    * @param Object          user_info       the user info for this input.
  156.    * @return boolean indicating if the input has been consumed.
  157.    */
  158.   public boolean anti_snap_feedback(
  159.     event           evt,     
  160.     Point           orig_pt,
  161.     Point           snap_pt,
  162.     int             feature_pt_indx,
  163.     snap_targetable target_obj,
  164.     Object          anti_snap_info,
  165.     Object          user_info);
  166.  
  167.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  168.  
  169.   /** 
  170.    * Indicate that the object is no longer anti-snapped to a given target 
  171.    * object.
  172.    *
  173.    * @param event           evt             the event "causing" the unanti-snap.
  174.    * @param Point           orig_pt         where this object should be without 
  175.    *                                        the anti-snap.
  176.    * @param Point           snap_pt         where this object was with the 
  177.    *                                        anti-snap.
  178.    * @param int             feature_pt_indx the feature point of this object 
  179.    *                                        that we were anti-snapping with.
  180.    * @param snap_targetable target_obj      the target object we were 
  181.    *                                        anti-snapping to.
  182.    * @param Object          user_info       the user info for this input.
  183.    * @return boolean indicating if the input has been consumed.
  184.    */
  185.   public boolean unanti_snap_to(
  186.     event           evt,
  187.     Point           orig_pt,
  188.     Point           snap_pt,
  189.     int             feature_pt_indx,
  190.     snap_targetable target_obj,
  191.     Object          anti_snap_info,
  192.     Object          user_info);
  193.  
  194.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  195. }
  196. /*=========================== COPYRIGHT NOTICE ===========================
  197.  
  198. This file is part of the subArctic user interface toolkit.
  199.  
  200. Copyright (c) 1996 Scott Hudson and Ian Smith
  201. All rights reserved.
  202.  
  203. The subArctic system is freely available for most uses under the terms
  204. and conditions described in 
  205.   http://www.cc.gatech.edu/gvu/ui/sub_arctic/sub_arctic/doc/usage.html 
  206. and appearing in full in the lib/interactor.java source file.
  207.  
  208. The current release and additional information about this software can be 
  209. found starting at: http://www.cc.gatech.edu/gvu/ui/sub_arctic/
  210.  
  211. ========================================================================*/
  212.